MacFormat 1995 January/macformat-020.iso/Shareware City/Graphics/Sparkle2.1.5 folder/(Docs)/README 2nd

Text File | 1994-09-04 | 44.3 KB | 872 lines | [TEXT/ALFA]

Sparkle: A new mac MPEG player.
-------------------------------
Documents for version 2.1.4
This document looks best in 9 point monaco.
On an MPW marks aware editor (like Alpha) this document has marks for
each section.

This document contains the following sections:
INTRODUCTION
LEGALITIES
SAVING TO MPEG
FAQs
WHY DOESN'T SPARKLE DO....
SMALL THINGS YOU MIGHT NOT HAVE NOTICED
THE FUTURE
HOW CAN YOU HELP IMPROVE SPARKLE?

------------------------------------------------------------------------------
INTRODUCTION

Hi there, friendly users. This is release 2.1.4 of my mac MPEG player.
Version 1.0 of this code was based on the Berkeley MPEG unix code.
(Anyone who wants to play with the Berkeley code can get it from
toe.cs.berkeley.edu in pub/multimedia/mpeg.) It was released as soon as
it was usable. This version no longer makes use of Berkeley code and uses
my own algorithms for greater speed, smaller memory footprint, and more
flexibility.

Version 2.0 of this code makes use of the Berkeley MPEG encoder, available
from the same place as above. Like version 1.0, this Berkeley code has not
been touched much except to make it Mac aware, object oriented, and thread
based. As a result, MPEG encoding is slow and a ridiculous memory hog
(what do you expect from UNIX coders---they seem to have no interest in
elegant design)?
As time permits I'll be going through that encoding code to make it faster
and use less memory.

Notice that there is a section of this document called FAQs.
Please read it before sending me mail, thus avoiding wasting your time and
mine.

Please read all of this document before playing with the program. While
actually using the program is pretty simple, there are a few things you
should be aware of. Many of you may not care when I waffle on about
technical details. However I would ask all programmer readers (especially
people knowledgable about QuickTime, and especially Apple [and
ex-Apple :-( employees] to look at the tech sections and help me out with
comments and suggestions. Each time someone gives me a pointer on how to
do something it cuts a week or more off the release date of the next
version of Sparkle.

Features:
•    Standard mac interface with menus and windows.
•    Uses the QuickTime movie controller to control the MPEG viewing.
•    MultiFinder friendly, with good backgrounding behavior.
•    Saves MPEGs to QuickTime movies.
•    Can open multiple files at once.
•   Can open QuickTime movies and sets of PICTs.
•   Can encode MPEGs.
•    Free.

To run it needs at least:
•    System 7.
•    QuickTime 1.6
•    A 68020 or better.
•    800K to play one 160x120 MPEG---to open more or large MPEGs increase the
    partition.
    Encoding MPEGs requires much more memory---about a minimum of 1600K for a
    160x120 source.
•    The Thread Manager. Right now, the Thread Manager is an extension
    that you can get from any friend who knows a lot about macs, or from the
    apple ftp site. Ftp to ftp.apple.com and look in
    dts/mac/sys.soft/extensions for Thread_manager_201.hqx
    I wish I could distribute it with Sparkle, but Apple's lawyers won't
    allow that.
    (Question for you as a user, does it make your Macintosh experience
    better or worse to find that a vital piece you need to run a program is
    not available with that program? Now try to explain that to Apple
    management, who sometime seem determined to make using a mac as difficult
    an experience as using a PC.)
    The Thread Manager may be built into System 7.5 when that's released, at
    which point you won't need the extension.

This program works fine, with good handling of errors, on my Quadra 610, but
that's the only machine I have to test it. If you find a bug that is not
caused by the various things listed below, please mail me with as many
details as possible, both about your machine and about what the  program
was last doing before it died on you.

I don't think there's much to say on the use of this program---you pretty
much run it like any other mac program. There is a section in this
document on tips that may not be obvious.
When opening files, you can choose to show all files, or only files with a
.mpg suffix.
If you choose the "show all files" option and open some random file, don't
be surprised when you are told that that is not a valid MPEG file.
If you set the option to change file types, the file type of the MPEG file
you are changing will be changed to a Sparkle file, which will give it a
nice icon and allow you to open the file by double-clicking on it.

Underneath the movie controller for each window is a progress bar which
will update itself when slow things are happening. If you have a fast
machine (say a Quadra or Centris) this won't have to update itself much,
except if you open large (and not too common) MPEGs---say 320x240. If you
really want to see what the progress update looks like, try having lots of
MPEGs playing at once, then switch Sparkle into the background.
If you save an MPEG to QuickTime using Cinepak, your machine may appear to
freeze while each frame is being converted. I have installed code to
reduce the extent of the freeze, but basically this is a bug with
QuickTime---the system just grabs control and won't let go for about five
seconds. Maybe this'll be fixed in QuickTime 2.0 if we're lucky.

I have tested this program extensively under low-memory conditions when it
opens files and plays them.  It should never crash under those conditions.
In 600K you can easily open, play and save to QT a 120x160 I-frame MPEG.  In
1500K you can open, play and save to QT a 320x240 IBP-frame MPEG.

Disk errors in various forms (bad sectors reading an MPEG file, no disk
space writing an QuickTime file, etc) will not crash, but the system will
put up an error alert and not handle the error very well (for example you
won't be given a chance to destroy old files to free up space on a disk).
Decent recovery from disk errors is on the list of things to do.

------------------------------------------------------------------------------
LEGALITIES

This program can be freely distributed.
If you want to include it on a CD-ROM collection, please ask me first,
but I'll probably allow you.
NOTE: Some authors will not allow their stuff to be distributed on CD-ROMs
for which people have to pay. I would ask these authors to consider things
more carefully. Many people (like myself) do not have very good ftp access
and a CD ROM of stuff is a godsend, even if we do have to pay a little for
it. Think about it.

If you feel a desperate need to thank me for this program, send me a
floppy of interesting MPEGs or QT movies you've picked up.
(Please don't e-mail me large files without warning.)
My paper-mail address is
    Maynard Handley
    ADI
    284 Stuart Street
    Dunedin
    New Zealand

------------------------------------------------------------------------------
SAVING TO MPEG

The dialog box offering options when you save to MPEG is not that great
right now if you don't know what you're doing. I'm sorry---I'll fix it
when I have time, like everything else.

For a better explanation of how MPEG works, read the Technical Notes file
in this package, but here are rough details.

When encoding your MPEG you will need to decide what types of frames you
want to use. If you want your MPEG to be read widely, ie on PC systems,
you should consider using only I-frames. The most common MPEG decoder on
PCs is the Xing decoder which only understands the simple I-frame MPEG
format. If you want to get the best possible compression you should use
I, P and B frames, but then your MPEG will only be able to be read by
smarter decoders. A compromise is to use only I and P frames. This will
give you a lot of the compression benefit of I, P and B frames, but will
be faster to encode.

If you don't want to know the details of these frames, choose a frame
pattern from the popup menu.
If you want to create your own frame pattern, here are some details:
(If you don't want to create your own frame pattern, ignore these.)
1) The first frame in the MPEG will always be I. That implicit I frame is
    displayed in front of the frame pattern text you enter because it is
    always there and you don't need to put it in. That implicit I frame is
    only used for the first frame, after that your pattern is repeated as
    necessary. Thus if your pattern is BBPBBI, the encoder will encode frames
    using the sequence I BBPBBI BBPBBI BBPBBI ...
    (For people who care about MPEG details, this is the playback order
    of the frames. The actual order of the frames stored in the file
    will be be I PBBIBB PBBIBB PBBIBB.)
2) If you are using B frames, you have to start off with two referential
    frames, the initial I frame then either an I or a P frame.
3) The last few frames of the MPEG, if they would be B frames, will be
    converted to I-frames. (If this didn't occur, like in the original
    Berkeley encoder code before I munged it, you will lose those final
    frames.)
4) Don't create too long a pattern of Ps or Bs. You'll start to lose
    quality and random access into the movie will become more granular. The
    presets I've given should guide you as to sensible selections.

Once you have chosen a frame pattern, you'll need to select the amount of
compression you want to use. This is set by the I, P and B quantization
levels. The values the dialogs gives as defaults will usually make sense
but if you want to change them:
1) The values are restricted to the range 1 through 31 inclusive.
    A quantization of 1 is the highest quality, a quantization of 31 is the
    lowest quality.
2) Normal quality is a quantization of about 8. Low quality is a
    quantization of about 16. High quality is about 6.

You can choose from various algorithms for generating P and B frames. I
haven't explored these in detail and they may change when I have time to
look at them. For now the important things to note are
1) They all seem to generate about the same quality, and about the same
    file size.
2) They are ordered in the menus by speed, with the fastest ones first.
3) The B-frame exhaustive search will take approx forever to do anything.
    Try it once to see what I mean, but don't expect to use it for anything
    useful.
As I explore these more and start diddling the code, I'll provide more
explanation.

If you save to MPEG, because of the non-causal algorithms used by MPEG
compression, frames are not compressed in the order they are displayed.
This means that if you are using B-frames and stop the compression before
it reaches the end of the source movie, the encoder may have queued up
some frames it needs to compress to make the MPEG file consistent.
If this is the case, Sparkle will have to encode those queued frame before
it stops the compression, so it won't stop immediately.
The message window will tell you how many frames have been queued so you can see
how things are going. If you have the speech manager installed, Sparkle
will also tell you how many frames are left, which you may find more
convenient.

You can set the frame rate from a popup menu. When the dialog box opens,
the frame rate of the MPEG or QT movie you are converting has its frame
rate read in and used to set the initial frame rate. So usually you won't
want to change the frame rate. Note that there are a limited set of frame
rates because MPEG only supports a very few frame rates. So the best one
possible is chosen.
Note also that frames are laid down with that frame rate which may cause
the movie to speed up or slow down. No frame interpolation is done to
ensure that perception remains correct across frame rate variation.
This'll be changed at some point, but is not a high priority compared to
sound.

When an MPEG is encoded the frame currently being encoded may be compared
to the original version of a previous frame, or to what you get when you
decompress the MPEG compressed version of the earlier frame. The latter
alternative is called ``Decoding Reference Frames''. If you use this
latter alternative the compression takes a little longer but results in
files a few percent smaller and slightly better quality. I'd recommend
you leave this option selected.

An MPEG can be encoded using using what are called half-pixels which means
that some pixels in a P- or B-frame are specified as an average of pixels
around them.  If you use half-pixels the MPEG created will be a few percent
smaller than if you don't use half-pixels and the quality will appear
better IF you play the MPEG on an MPEG player that handles half-pixels.
However if you use an MPEG player that does not understand half-pixels the
result may look pretty shabby in places where there is a lot of action.
Also, using half-pixels makes encoding slower and increases the amount of
memory used by almost two-thirds. For these reasons I'd recommend not
selecting this option.


Earlier versions of Sparkle required massive amounts of memory to encode
MPEGs. This has been improved substantially in 2.1.4. There is still room
for improvement but that will have to come later

At present MPEG encoding requires a huge amount of memory. As I find time
I'll reduce this substantially. At present, the following will give you
an idea of how much memory you need to encode an MPEG.
Let the width of the MPEG file you wish to encode be w (say 160) and the
height be h (say 120).
Then for an MPEG comprised of only I-frames you will need 4.5*w*h bytes of
RAM for encoding
(with the example numbers given this is 4.5*120*160 = 4.5*20K = 90K).
For an MPEG comprised of P-frames you will need 15*w*h bytes of RAM and
for an MPEG comprised of I-, P- and B-frames you will need 22.5*w*h bytes
of RAM.
There may be a few odd bits and pieces added to this, maybe another 5% or
so, but this should give you order or magnitude.
In addition to this RAM for the encoding you will need the RAM used by
the Sparkle application (around 400 K) and the RAM used by the QuickTime
movie or whatever your source is which is probably a few hundred K. You
can probably take these base requirements together as about one MB or so.

If you don't use half pixels the numbers are reduced.

Scale factors
                        Without half-pixels        With half-pixels
            I           IP          IPB            IP            IPB
w*h*       4.5          9          13.5         15          22.5


So for some standard sizes:
                        With half-pixels        Without half-pixels
            I           IP          IPB            IP            IPB
160x120     90K        180K        270K        300K        450K
320x240    360K        720        1.08M        1.2M        1.8M
640x480   1.44M       2.88M       4.32M        4.8M        7.2M


------------------------------------------------------------------------------
MENU OPTIONS

Here are various points related to the menu options:

• File| Save As:
    This allows you to start saving a movie or pseduo-movie
    (made from a set of PICTs) as an MPEG or QuickTime file. Once you start
    the save it continues in the background. This menu item changes to
    File| Stop Saving which will stop the saving at once.
    You may want to pause the saving but not stop it, for example so that
    you can play another movie at top speed. To pause, simply click anywhere
    in the movie controller or type any key.
    When the saving is busy working away the movie controller play button
    shows a pause symbol, because if you click there it will pause the saving.
    When the saving is paused, the movie controller play button shows a play
    symbol because if you click the saving will resume.
• Image|Grow or Shrink
    The scaling of the window at any time is given in the title bar.
    When the title starts with *1, the movie is its natural size.
    With *2 the movie has been doubled in size.
    With /2 the movie has been halved in size.
    For now if you expand or shrink movies beyond their natural size
    playback will be much slower and quality may not be as good. I'll be
    adding code to fix this soonish.

• Image| Hide All
    You can hide or show all the decorations below the movie windows. The
    easiest way to do this is with the tab, shift-tab and control-tab keys,
    or with command-H. You may want to do this because the decorations
    irritate you or because hiding the decorations makes playback speed a
    few percent faster.

• Playback| Play All Frames:
    If this is set, every frame of the movie will be played. The movie will
    try to play in real time, but may be slower than real time if necessary.
    It will never be faster than real time.
    With quicktime movies sound is disabled when this option is on.
    When this option is off, the movie will play back in real time which may
    mean skipping some frames. For MPEGs, how well this works depends on how
    fast your mac is. (Also read the section on play rate below.)

• Playback| Play at Double Speed:
    These options set the  movie to play twice as fast, at the normal rate,
    or twice as slowly. Note that if Play All Frames is active, playing the
    movie at double speed may be no faster than playing it at normal speed
    because both ways the calculation of each frame is overloading the mac.
    Some MPEGs look jerky and too fast when played at their normal speed and
    with Play All Frames switched off. This is because the MPEGs have been
    encoded at too high a frame rate. For example the original movie may
    been sampled at 12 frames per second but it's encoded as an MPEG of 24
    (or 23.976) frames per second. This happens because the lowest possible
    frame rate with MPEG is 23.976 fps. So if this happens, you may want to
    set the MPEG to play at half speed.
    You can also control the speed at which movies play by command-clicking
    in the steppers of the movie controller.

• Edit| Preferences| Faster Mode:
    If you set this option, whenever Sparkle is busy, either playing movies
    or encoding movies, it will not yield time to background applications.
    This makes playback a little faster and smoother.
    However if you have an application doing something in the background,
    for example a modem download or a background compile, you might want to
    deselect this option.
    By my testing, when Faster mode is on Sparkle uses up about 90% of the
    CPU. When faster mode is off Sparkle uses up about 70% of the CPU.
    (When Sparkle is in Faster mode it still has to use the EventAvail() trap
    every so often to see if the user has issued a command, moved the window,
    grown it or whatever. It's these calls to EventAvail() which can yield the
    CPU to other processes that suck up the 10% of the CPU not used by
    Sparkle in Faster mode. Anyone know how to perform the equivalent of
    EventAvail() without allowing the Process Manager to yield?)

------------------------------------------------------------------------------
MPEG PLAYBACK PREFERENCES

The MPEG Playback Preferences dialog (use command-R or look under the
Preferences menu under the Edit menu) allows you to set general playback
preferences. Most of these are concerned with how you wish to balance
playback speed against playback quality. Note that whatever settings you
choose for playback, when you save an MPEG file to another format all
settings are switched to the highest quality while the save is in
progress, so you don't need to worry about losing quality that way.

• Clip YCrCb:
    What this refers to is an intermediate stage in the MPEG decoding. The
    values for Y, Cr and Cb should be between 0 and 255 but some MPEGs are
    encoded so that some Y or Cr or Cb values are calculated to be below 0
    or above 255. If you don't select this option, Sparkle doesn't check the
    Y Cr Cb values and clip them if they are out of bounds. This makes
    playback about 10% faster, but may (if the values are out of bounds)
    lead to dots of incorrect color or black dots in areas of white or
    suchlike.

The other quality options are used depending on the screen depth of the
screen on which the MPEG is playing. So if your MPEG is on a 16-bit
screen, the 16-bit color options are used.
• Use 4x4 IDCT:
    One time-consuming part of MPEG decoding is the IDCT which is somewhat
    like a Fourier transform. This should be performed using a matrix of 8x8
    coefficients. If you select this option only a 4x4 subset of that matrix
    will be used. This makes the calculation a lot faster, but the cost is
    some blurriness to the image which is usually acceptable.
•Use half-pixels:
    Half-pixels are a scheme whereby certain pixels in the image are
    represented in the MPEG file as an average of nearby pixels. Calculating
    these averages takes time but improves quality. I'd recommend not
    bothering with half-pixels on an 8-bit color screen because the dithering
    hides the fine detail they reveal. For other screen depths you decide.
    Some MPEGs will not be affected by this setting, because they were coded
    not to use half-pixels.

• 24-bit screens display options:
    The high quality setting corresponds to clipping RGB while the faster
    setting does not clip RGB.
    This is the same sort of issue as the Clip YCrCb note above, only
    occurring at a later stage in processing. Some MPEGs look fine with
    neither form of clipping, some only need one or the other, and some need
    both. (This option is not an issue for 8 and 16 bit screens because they
    use a different way of calculating RGB for their display---not as high
    quality as the 24-bit method, but good enough for the given screen
    depth.)
• 8-bit color screens display options:
    You have a choice of three dither options on an 8-bit screen.
    * Fast dithering uses an algorithm I invented. It is phenomenally fast,
    but not the greatest quality. It looks especially bad for things that
    need very sharp edges, like text. (It also uses 128K of storage to do its
    thing, so if you're low on space you may want a different option.
    When this option is activated for the first time --- for example when
    you switch to 8-bit colors screen depth from some other depth, or when
    you first open an MPEG under 8-bit screen depth --- these 128K of tables
    have to be calculated which takes about 1.5 sec on my Quadra 610.
    In a future version of the code I'll implement ideas I have for removing
    this delay.)
    * Use 16-bit pixmap calculates everything using a temporary 16bit pixmap
    which is then dithered on the screen using QuickDraw. It's a compromise---
    the quality is better than fast dithering and it uses less memory than
    the 24-bit scheme.
    * Use 24-bit pixmap works like 16-bit pixmaps, but all calculations are
    performed on a 24-bit pixmap (using RGB clipping).
    This gives the best results, but is slower than the 16-bit pixmap case and
    uses more memory.
    * I hope to improve the quality of the fast dithering algorithm in the
    near future.
    * Also at some point I'll add code to allow you to set an optimal palette
    when playing on 8-bit color screens. At present I simply use whatever
    palette the screen is using, usually the system palette.
• 16-bit screen display options:
    You have three options.
    * The fast option uses a lookup table directly on the MPEG YCrCb data to
    get RGB values. This is faster but gives lower quality.
    * The 16bit high-quality option calculates the RGB values properly (with
    greater precision than using a lookup table). It gives better quality
    but is slower. (At present I haven't yet written the code for this
    option so it is disabled.)
    * The 24bit pixmap option calculates results using a 24-bit pixmap (and
    RGB clipping), then dithers the result to the 16bit screen. It gives the
    best quality but is slowest.

• For 8-bit grey screens:
    Two points to note.
    * Is your graphics card set to grey mode? If you have a grey screen but in the
    monitors control panel you have set your graphics card to color, Sparkle
    will think it's on an 8-bit color screen. This will give you slower
    playback and lower-quality results.
    * For the fastest possible playback, I assume that the screen palette is
    set to the system palette. On an 8-bit grey screen there is never any
    reason to change this. Nonetheless, some applications feel they simply
    have to perform this pointless exercise whose only effect is to reduce
    the quality of what's displayed by other applications. (Would you be at
    all surprised to learn that Word, one of the masterpieces from those
    geniuses at Redmond, is such an application? I though not.)
    What this means is that if you are running Word (or another of these
    ill-behaved applications) in the background, Sparkle will playback MPEG
    files somewhat slower than it should.

In summary:
The fastest playback possible is on a 8-bit grey screen, followed by
  8-bit color, then 16-bit color, then 24-bit color.
For fastest playback, deselect the ClipYCrCb option,
  select the Use 4x4 IDCT option,
  deselect the Use Half-Pixels option
  for 8-bit screens use fast dithering
  for 16bit screens use 16bit fast
  for 24bit screens use 24bit fast
  use command-H to hide all the decorations below the video window.
For highest quality playback, use the deepest screen-depth you can,
  select ClipYCrCb
  deselect the Use 4x4IDCT option,
  select the Use Half-Pixels option
  select the 24-bit pixmap option

Decoding MPEGs requires lots of computation, but can be made faster by
sacrificing some quality. I've tried to allow you to make your own choice
about which you prefer. But remember I can't work miracles. For example I
can't magically give you an 8-bit color dither algorithm that gives the
same quality as the QuickDraw but runs at the speed of my fast dithering.
I'll try to improve the quality of the high-speed options in future, but
I can't promise anything.

The one other item in this dialog box is the
"Prefer 8-bit color to 8 bit-grey" checkbox. This is only relevant to
people who have more than one screen, at least one of which is grey and
at least one of which is color.
When Sparkle opens a file it orders all the screns available by screen
depth and tries to open a window on the deepest depth screen. But if you
have one screen set to 8-bit grey and the other set to 8-bit color it
can't know which you'd prefer, hence this setting. You may prefer the
color screen because any color is better than none, or the grey screen
because it gives faster playback and no fuzziness from dithering.
(After ordering the screens by depth, Sparkle notes where other movie
windows have been placed and tries to place the new window so it doesn't
overlap any of the old windows. Also, if the window opened is large than
any screen, it will be opened at half size or whatever so it does fit on
the screen. I hope you like this algorithm. It works better than what
every other program I've seen uses. If you have comments about it, please
mail me.)

------------------------------------------------------------------------------
PICT FILES AND PSEUDO-MOVIES

Sparkle can open a set of PICT files to convert them to an MPEG or QT
movie. This may be useful if you have enough program, like a graphing
program, that creates a set of PICTs, or if you have a set of medical
scans or such.

The only picture format Sparkle understands is PICT, the Mac standard
picture format. I do not plan to change this because there are lots of
programs out there, many of them free and many of them capable of running
in batch, that will convert whatever format you have to PICT.

Once you have your pictures in PICT format, they need to be in the same
folder and given the same name so that Sparkle can link them together.  For
example, if these pictures represent x-rays of your head, call them
myHead.1, myHead.2, etc.  They must be named name.# where name is common to
all files and # is a number.  The numbers don't have to start at zero or
one, and don't have to be contiguous.  However they must all be positive
integers.

From the open files dialog open one of your PICTs---whichever one you get
to first, it doesn't have to be the lowest numbered one. Sparkle will
scan the folder for other PICT files with that name and a number added,
order the files it finds, and display them all in a movie window.
You can now treat this pseudo-movie like any other movie. You can grow or
shrink the window, step forwards or backwards, etc. You can play the
movie if you like, but for these PICT pseudo-movies I set the framerate
to only one frame per second. Decoding a PICT can be fairly slow---it
involves disk access and lots of memory---so don't expect this to work
wonderfully. You can now save the pseudo-movie as an MPEG or QT movie
just as you would normally.

The PICTs may be different sizes, but the window opened will be the size of
the PICT you select in the open file dialog box. The other PICTs will be
scaled to fit this size window and may not look too good. I wouldn't
recommend using a set of PICTs that aren't all the same size.

Note that for now I don't do anything special when I draw the pictures.
In particular this means on screens that aren't 24-bit or 16-bit I don't
dither the picture. This will be fixed fairly soon. For now everything
all works and it doesn't affect the quality of movies you create.
I'll also be adding code to save MPEGs or QuickTime movies as a set of
PICTs fairly soon.

------------------------------------------------------------------------------

QUICKEYS AND BATCH CONVERSION

I won't have AppleScriptability in place for a few months, but I have
been asked by some users for a rudimentary support for batch conversions.
Specifically people wanted a way for Sparkle to indicate that it was done
encoding a given file.

I have provided such a capability for QuicKeys users in a very crude
fashion. When Sparkle has finished converting a file to a different
format it will toggle the cursor from the standard arrow cursor to a
thick cross for one second.
Note which cross this is: It is not a thin one pixel wide cross, neither is
it a spreadSheet like cross with arms a few pixels wide. This cross has
arms that are two pixels wide.

To use this capability in QuicKeys, you want to put in your sequence a
Wait..  command. Make the Wait command a WaitForCursor variant, and set
the options to wait until the cursor becomes ``Other...''. In the
``Other'' dialog box choose the appropriate cursor---in my version of
QuicKeys it's the fourth cursor along. UnSet the Test for Mask box and
set the Test for Cursor box.

I would recommend that you structure your sequence like this:
    Wait ...      ---Wait for the cursor
    Pause...    ---Pause for a second
    Pause...    ---Pause for five seconds or so
    Do your thing.

The first pause in the above is to wait until Sparkle finishes its one
second flash of this cross cursor. The second is to wait for general disk
activity and such to finish. At that point you can then go on to whatever
the rest of your sequence does, like maybe close Sparkle then open it
again with a new file.

------------------------------------------------------------------------------

FAQs (Frequently asked questions).

• I try to play MPEGs but my Mac starts speaking numbers or asks me over and
over to select a voice.
    You have the Speech Manager installed on your Mac including a little
    extension called ``Speech Media Handler''. Speech Media Handler speaks
    the text of movies that include a text track, and Sparkle plays MPEGs
    by creating a dummy text track as part of the process of faking QuickTime
    into accepting MPEGs. I'd recommend ditching Speech Media Handler. I've
    never seen a place where it is useful and right now it's kinda a cute toy
    idea that escaped from Apple. Maybe in a few months they'll give it a
    programmer interface and make it more useful.

• I've downloaded (or uploaded) an MPEG using Mosaic/WWW and when I try to
play it Sparkle says it's not an MPEG file. But if I ftp the file with
Fetch or suchlike it works fine. What's happening?
    Be very careful when transferring files over the Internet with MacBinary.
    Fetch and many such programs automatically strip MacBinary from files,
    but Mosaic does not appear to (maybe this will be fixed soon). So
    if an MPEG is stored at a Mosaic site using MacBinary, all Mosaic users
    trying to download it will have problems.

• Why when I try to step back one frame do I sometimes step back 5 or six
frames?
    You are viewing an MPEG with P or B frames. Because of the way these
    frames are compressed, it would take a lot of computation (ie be slow) to
    jump exactly to the frame you want, so I jump to the nearest frame that
    can be calculated at reasonable speed. If you want to know more, read the
    technical note in this package.
• Why when I try to random access a frame do I get sent to the same set of
frame numbers always?
    Same reason as above.

• Why does my MPEG have the occasional block of garbage, mostly colored
green?
    Some part of the MPEG file has become corrupt. This usually happens with
    MPEG files that have been uuencoded and have had a character or two lost
    or changed.
• Why are large parts of my MPEG filled with green garbage, or with parts
of earlier scenes.
    You have probably downloaded the MPEG file using gopher or ftp in ASCII
    format. The file is now useless. Download it again using BINARY mode.
    Better still, set your gopher or ftp application always to download .MPG
    suffix files in BINARY---don't trust its AUTOMATIC mode.
• Why is the first frame of my MPEG all green?
    Some people out there when they create an MPEG file, randomly start it
    where they feel like it.
    The consequence is that the first some bytes of the file are garbage and
    appear as an all green first frame.
    If you have one of these MPEGs, whenever you jump to the first frame, you
    won't see the first frame, but simply the last frame you were looking at. This
    is a consequence of the way Sparkle handles errors in the MPEG file format.
    Mostly it works well, but in this particular case it isn't great.
    It is not too easy to work around this because of the many different ways
    in which the MPEG can have garbage at the start before valid data begins.

• Why at the end of an MPEG is the last frame the same as the second to
last frame?
    Some MPEGs just are created this way, with the last two frames as
    duplicates. This is a problem with those files, not a bug in Sparkle, and
    one just has to accept it.
    A similar type problem is that some video that's been converted to 30fps
    from 24fps film has duplicate frames every so often, and agin one just
    has to accept this for now.

• What does the Thread Manager do? Why do you make such a fuss over it?
    The Thread Manager provides a way for a programmer to create a number of
    tasks within an application and have those tasks all run together. So
    with Sparkle every time the user asks for something that will takes some
    time, like playing an MPEG or saving a file in some different format, I
    create a task that does that work. If the Thread Manager isn't present,
    you, the user, can't create a number of these tasks and switch between
    them---you are restricted to doing only one thing at a time.

• When I started saving a file to MPEG, it got through two frames then sat there
doing nothing for a long long time. Did it crash?
    Especially when saving to MPEG, Sparkle creates a large number of blocks
    of memory. If the mac runs out of memory partway through performing
    this saving, it will run around trying everything it can to scrounge memory.
    On my Quadra 610 I have seen it sit there for 45 seconds trying to free up
    memory before it concludes that there's nothing it can do and pops up an
    error message. I guess on slower machines it might sit there for up to two
    minutes. Just be patient and wait a while before concluding things
    have crashed.

• Will you create a PowerPC native version? A version that uses the DSP in
the AV macs?
    I don't have a PPC or an AV mac, and unless someone buys me one, I won't
    have either for sometime. Maybe when Symantec offer a Think C 7 that
    compiles to PowerPC, someone out there with a PowerPC will be able to
    do the compile for me. Until then, I'm afraid this is all that I can do.

• Where can I get MPEG files?
    An ftp sites is 2k-ftp.CS.Berkeley.EDU in pub/multimedia.
    (This site used to be called toe.cs.berkeley.edu.)

    Here are some WWW sites
    http://www.ccsf.caltech.edu/~johns/sl9.html  (CalTech)
    http://newproducts.jpl.nasa.gov/sl9/images.html  (JPL)
    http://seds.lpl.arizona.edu/sl9/sl9.html  (U. Arizona)

• Where can I find more about MPEG?
    Read the UseNet MPEG FAQ. This is published in news.answers every so
    often, and can be ftp'd as
        host: ftp.cs.tu-berlin.de
        file: /pub/msdos/windows3/graphics/mpegfaXX.zip
    (XX is a version number).
     Yeah, it's a zip file and that sucks, but that's life. There are a bunch
     of mac deZip'ers around so grab one and use it.
     The latest version of this file as of July 94 to be 3.1.

• How can I deal with AVI files?
    At mac.archive.umich.edu (and probably at sumex)
    in /mac/graphics/graphicsutil is vfw1.1utilities.sit.hqx
    which handles AVI files and is supposed to work pretty well.


• Do I know of a program that ...?
    Not really.
    I know of no Mac program that handles MPEG sound, or MPEGs with a .WAV
    file. There is source code floating around that converts MPEG sound to
    and from 16bit 44.2kHz samples, but it does not deal with MPEG
    video/audio synching and thus isn't yet of much use.
    I know of no Mac program that can play windows AVI files.
    My next major task is handling sound.
    But until I am done with that, I'm afraid you're out of luck.

------------------------------------------------------------------------------
WHY DOESN'T SPARKLE DO...

•    Why doesn't Sparkle read .gl, .dl and .fli files?
One reason is that those file formats are awful. They give these dinky
low contrast horribly dithered images no-one would want to look at, and
they usually only have about 10 frames. Maybe, years from now, I'll add
those conversions, but they're about as low a priority as you get.
At mac.archive.umich.edu (and probably at sumex)
in /mac/graphics/graphicsutil is macanimviewer1.01.sit.hqx
which handles these various cheapo formats so you might want to grab it.

•    What about audio?
MPEG has audio compression as well as video compression. I've been doing
lots of reading into this and pretty soon will start coding for it.

•    What about Video for Windows?
I would be nice to support .AVI files. But right now I know nothing about
.AVI beyond the fact that it exists. Again any info anyone has is
appreciated. Until I know how .AVI works, how it fits into the windows
environment etc, I can't even tell you if it's practical for Sparkle to
try to support .AVI, let alone start the necessary coding.

•    Why don't you write an MPEG codec?
Under QT 1.x there was no compelling need for this and no way to do it.
QT 2.0 has some hooks for the use of MPEG. However when I tried beta's of
QT 2.0 on MPEG handling they consistently crashed. So for now I'm waiting
until the QT 2.0 MPEG framework is stable and actually works. When that
happens I'll consider things again.

•    Will I make the source available?
Yes, at some point. I had hoped to do so this release, but while the code
is 95% clean and readable, it's still not perfect, and don't yet think
it would help anyone much.

------------------------------------------------------------------------------
SMALL THINGS YOU MIGHT NOT HAVE NOTICED

The movie controller behaves pretty much like a standard QT controller.
You can step forward and backwards, hold down those buttons to play
forwards or backwards and click or drag in the central region to go to a
random point.
You can use the forward and backward arrow keys to step.
You can option click in the forward and backward steppers to go to the
beginning or end of the MPEG. Likewise using option forward or backward
arrow.
You can start the movie playing using either return, spacebar, or
command forward arrow. You can stop playing using spacebar or return.
You can yet play backwards by using command backward arrow.

The visual clue that the movie is being saved is that
the movie controller loses its controls and shows only a relative position.
This is not a particularly obvious fact and may at some point be changed.
For now it works once you realize this fact.

When a movie is being saved, you can either stop the conversion
or pause it. To stop the conversion, use command-S (or the equivalent
menu option.) This will save the movie using the frames created so far.
To pause the conversion use command-P, or the equivalent menu option, or
click in the movie controller.
The  saving will stop until you start that movie playing again. This is
occasionally useful if you want to pause a cinepak conversion to do a
short job on your mac.
You can tell whether a movie is actively being saved or paused being
saved by looking at the indicator in the title bar.
If the first character in the title bar is
  S the movie is actively being saved,
  P the movie is paused being saved,
  R the movie is in realtime playback mode
  A the movie is in play-all-frames playback mode.

If you are partway through a movie and save, the movie will be
rewound to the beginning for you. You do not need to be at the start of a
movie to save.

You can set the temporal quality options when saving to QuickTime
separately from the spatial quality options. If you need to do this, hold
down the option key while using the quality slider, and it will become a
temporal quality slider.

------------------------------------------------------------------------------
THE FUTURE

The basic outline for now is
    2.5 Cleaned up faster, smaller version of 2.0.
    3.0 Handles sound.
    3.5 Cleaned up faster, smaller version of 3.0.
While adding these large additions I'll fix small things as I go, and as
I have time. I don't see the user interface improving much for some
time---more important things need my time.

I also want to add stuff to allow us to create movies. Morphs, special
effects, that sort of thing.

------------------------------------------------------------------------------
HOW CAN YOU HELP IMPROVE SPARKLE?

•    Any info on psycho-acoustic encoding?
•    Any info on Microsoft Video for Windows?
•    Any bug reports.
•    Any ideas you have or suggestions. Your suggestions may go onto the
    list of things to do (currently two pages of single line items) but will
    probably be acted upon at some point. People have suggested several
    things to me I would not have thought of myself, so I do want your
    feedback.
------------------------------------------------------------------------------
THANKS

* Many people all over the internet have helped me write this code.
* Thanks to the people at Berkeley. Even though I've completely replaced
    their MPEG playback code with my own, they helped get this project started.
    And, until I rewrite it, I'm using their MPEG encoding code.
* Thanks to various usenet personalities who answered mac programming
    questions, mailed me quicktime header files and such. Special thanks to
    ldo in New Zealand, and Jon W{tte in Sweden, and bryanw, keeper of the
    MPEG FAQ, who mailed me about the Stanford MPEG encoder.
* A special individual thank you goes to DS (he didn't want me to give his
    name but he knows who he is.) DS mailed me a CD ROM and ten floppies of
    information about QuickTime components after I complained that Apple was
    not making this information easily available. He's also provided me with
    information on QT 2.0 which will gradually be assimilated into Sparkle.
* Thanks to Gene Chalfant who passed on a paper from NASA containing some
    interesting ideas on IDCT alternatives.
* Thanks to the mystery person in Britain who sent me some QT 2.0
    information in an envelope with no name attached to it.\
* Thanks to Jamie McCarthy for code for touching Finder folders.
* Thanks to Troy Gaul for the Infinity Windoid.
* Thanks to Richard Lim for the current set of icons used by Sparkle.
    (Which I modified a little so it's probably best to blame me rather than
    him for poor design choices if you don't like them.)
* Thanks to Stuart Cheshire for mailing me a QT 2.0beta CD-ROM and misc
    useful info.
* Thanks to everyone who's mailed in bug reports or suggestions. Even when
    I can't implement suggestions at once, they go on the list for inclusion
    in a few months.
* Thanks to Apple for making the greatest computers in the world.
    (Though sadly they seem to be going completely clueless with regard to
    how to distribute their various new ideas. I fear if they don't get their
    act together about this soon, NO-ONE will support these new things
    because developers will have no idea whose machine has what on it.)
* Thanks also to Symantec for creating such a great programming environment.
    This program was written with Think C 5, then Think C 6  and now Think C 7
    using the Think Class Library. Having coded on Windows, X-windows, and
    the Mac, I can unreservedly say that the Mac is by far the most pleasant
    platform for a programmer.

(If I've forgotten your name here by mistake and you really deserve to be
here, please remind me.)

Maynard Handley
[e-mail]
September 04 1994